{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# In this notebook you will learn about the redispatching capabilities offered by grid2op."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Objectives**\n",
    "\n",
    "In the previous notebooks, we presented actions in a discrete action space. However, more actions are available in Grid2Op. Redispatching is a kind of continuous action that will be described here.\n",
    "\n",
    "This notebook will:\n",
    "\n",
    "- present what redispatching is\n",
    "- show how it can be used in grid2op\n",
    "- detail the redispatching actions\n",
    "- show an example of a redispatching Agent."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import sys\n",
    "import grid2op\n",
    "from grid2op.Agent import DoNothingAgent, BaseAgent\n",
    "from tqdm.notebook import tqdm\n",
    "import numpy as np\n",
    "max_iter = 100  # to make computation much faster we will only consider 100 time steps\n",
    "import pdb\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Impossible to automatically add a menu / table of content to this notebook.\n",
      "You can download \"jyquickhelper\" package with: \n",
      "\"pip install jyquickhelper\"\n"
     ]
    }
   ],
   "source": [
    "res = None\n",
    "try:\n",
    "    from jyquickhelper import add_notebook_menu\n",
    "    res = add_notebook_menu()\n",
    "except ModuleNotFoundError:\n",
    "    print(\"Impossible to automatically add a menu / table of content to this notebook.\\nYou can download \\\"jyquickhelper\\\" package with: \\n\\\"pip install jyquickhelper\\\"\")\n",
    "res"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to implement redispatching actions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Having a suitable environment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, some environments do not specify the cost of generators, their maximum and minimum production values, etc. In this case it is not possible to redispatching in grid2op.\n",
    "\n",
    "To know more about what is needed for using redispatching, it is advised to look at this help online : https://grid2op.readthedocs.io/en/latest/space.html#grid2op.Space.GridObjects.redispatching_unit_commitment_availble for the most recent documentation. When this notebook was created, what was needed was:\n",
    "\n",
    "- \"gen_type\": the type of generator\n",
    "- \"gen_pmin\": the minimum value a generator can produce\n",
    "- \"gen_pmax\" : the maximum value a generator can produce\n",
    "- \"gen_redispatchable\": whether this generator can be dispatched\n",
    "- \"gen_max_ramp_up\": the maximum increase of power a generator can have between two consecutive time steps\n",
    "- \"gen_max_ramp_down\": the maximum decrease of power a generator can have between two consecutive time steps\n",
    "- \"gen_min_uptime\": the minimum time a generator needs to be turned on (it's impossible to disconnect it if it's not connected for a least \"gen_min_uptime\" consecutive time step)\n",
    "- \"gen_min_downtime\": same as above, but for downtime\n",
    "- \"gen_cost_per_MW\": the generation cost. For each MW of electricity produced in a time step, this is the amount paid\n",
    "- \"gen_startup_cost\": the cost to start a generator\n",
    "- \"gen_shutdown_cost\": the cost to shutdown a generator\n",
    "\n",
    "We made available a dedicated environment, based on the IEEE case14 powergrid that has all this features. It is advised to use this small environment for testing and getting familiar with redispatching.\n",
    "\n",
    "This environment includes 5 generators, as the original case14 system. It has one solar generator and one wind generator (that cannot be dispatched), one nuclear powerplant (dispatchable) and 2 thermal generators (also dispatchable). Thus, redispatching is a problem of continuous control with 3 degress of freedom here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/benjamin/Documents/grid2op_dev/getting_started/grid2op/MakeEnv/Make.py:240: UserWarning: You are using a development environment. This environment is not intended for training agents.\n",
      "  warnings.warn(_MAKE_DEV_ENV_WARN)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Is this environment suitable for redispatching: True\n"
     ]
    }
   ],
   "source": [
    "env = grid2op.make(\"rte_case14_redisp\", test=True)\n",
    "print(\"Is this environment suitable for redispatching: {}\".format(env.redispatching_unit_commitment_availble))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, this environment is suitable for redispatching. It means that all quantities described above are set (and visible).\n",
    "\n",
    "In the L2RPN 2019 challenges, we rewarded participants based on the use of the powerlines. In next challenges, or for other uses of this platform where redispatching should be considered, it's better to consider the economic cost of the sytem as an evaluation metric. However, usually a cost should be minimized, while a reward should be maximized. To take this into account, a simple reward named \"EconomicReward\" has been created. It has the following properties:\n",
    "\n",
    "- it returns -1 if there has been a game over\n",
    "- otherwise (there has been no game over, no errors, etc) it is always strictly positive\n",
    "- maximizing this reward is equivalent to minimizing the cost\n",
    "\n",
    "Note that this reward doesn't take into account the cost to perform a redispatching action. This reward can be used to build what is called an \"economic dispatch\", a problem that is particularly interesting for electricity producers but of lower interest for Transmission System Operators (as opposed to the topology).\n",
    "\n",
    "Compared to standard \"economic dispatch\" problems, for now storages are not implemented (coming soon) and we don't fully take into account the startup cost, shutdown cost, as well as minimum downtime and minimum uptime (even though all of these features are implemented). Also, note that redispatching is implemented in differences, meaning that you first need to provide an economic dispatch, and then think in terms of variations from that point onward. This is the usage that will be explained in this notebook. For real unit commitment / economic dispatch problems, the key words \"injections\" / \"prod_p\" for the action would probably be more suited."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Redispatching implementation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Unlike topological actions, that are always feasible (this is an assumption that is made in this package), redispatching actions are limited by physical constraints on the generators. For example:\n",
    "\n",
    "- it is not possible for a generator to produce more (resp. less) than pmax (resp. pmin). Unlike the curent flow on the powerline, this is a strict physical constraint.\n",
    "- it is not possible, for the same physical limitations, to increase (or decrease) too much the value between two consecutive time steps.\n",
    "- redispatching actions stack with one another. It means that if you ask to increase the production of the generator 1 by $10MW$ at time step t, and by $20MW$ at time step $t+1$, it means that the set point at time step $t+1$ will be $+30MW$ higher than if no redispatching had been made (it would have been only $+10MW$ higher if the second redispatching action had not been performed).\n",
    "\n",
    "That being said, a lot of thing can happen, that make redispatching a bit less trivial than topology:\n",
    "- When you do a redispatching action, you don't know what the time series of the environment look like. For example, say the pmax of generator 1 is 100. The setpoint of this generator at time t is $60MW$, and you want to increase its value by another $40MW$. This action is legal: $60+40 \\leq pmax (=100) $. So at time $t$ everything is fine. Now let's suppose that the environment also moved the setpoint of this same generator from $60$ to be at $70MW$ at time $t+1$. With the redispatching action, this would mean that the setpoint would be $70+40 = 110 > pmax$. This is not possible. In this case, the redispatching action will be capped : instead of the desired redispatching of $+40$, only a smaller redispatching of $+30$ will be implemented on the powergrid. \n",
    "- Another problem can arise with the fundamental principle of power grid: power energy cannot be stored in a grid. At each time we then have $\\sum \\text{Prod} = \\sum \\text{Load} + \\text{Losses}$. In this competition, the data is generated such that this condition holds (approximately) for all time steps. This means that if you ask for a redispatching of +xxx MW on a given generator, then the other ones must compensate and \"absorb\" xxx MW such that it sums to 0 overall.\n",
    "\n",
    "Out of simplicity for the participants, there are some \"automatons\" that automatically transform an proposed redispatching action into a valid redispatching action. These automatons basically ensure that the two above-mentionned conditions hold. It explains the differences between \"target_redispatching\" which is the desired setpoint enter by the agent, and the \"actual_redispatching\" which is the one that has actually been implemented on the powergrid after it has been corrected by the automatons."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### More cases for ambiguous actions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ True,  True, False, False,  True])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "env.gen_redispatchable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above vector tells which generator is dispatchable and which is not. Any attempt to dispatch a generator that is not dispatchable leads to an ambiguous action."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(True,\n",
       " Grid2OpException AmbiguousAction InvalidRedispatching InvalidRedispatching('Trying to apply a redispatching action on a non redispatchable generator'))"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "act = env.action_space({\"redispatch\": [(2,+10)]})\n",
    "act.is_ambiguous()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we see, this action is ambiguous because we are `Trying to apply a redispatching action on a non redispatchable generator`. Indeed, as shown above, the generator 2 is not dispatchable.\n",
    "\n",
    "Generators also have physical constraints. You cannot ask them to change the active production value too fast, this would damage the generator, and breaking a nuclear plant is often a terrible idea. In grid2op it is implemented as an ambiguous action. Trying to go beyond this value will result in an ambiguous action.\n",
    "\n",
    "This value is called the \"ramp\" and it's available through the \"max_ramp_up\" attribute. On the next cell, you can see that the ramp is $5MW$ for the first generator and $10MW$ for the second one and the last one. For the other 2 it's irrelevant because they are not dispatchable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 5., 10.,  0.,  0., 10.], dtype=float32)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "env.gen_max_ramp_up"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Any attempt to go beyond this value will raise an ambiguous error :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(True,\n",
       " Grid2OpException AmbiguousAction InvalidRedispatching InvalidRedispatching('Some redispatching amount are above the maximum ramp up'))"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "act = env.action_space({\"redispatch\": [(0,+10)]})\n",
    "act.is_ambiguous()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the previous action, we asked the generator 0 to increase its setpoint by $10MW$. However, its maximum ramp up is only $5MW$. Thus, this action is ambiguous.\n",
    "\n",
    "Of course, there are some perfectly valid redispatching actions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(False, None)"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "act = env.action_space({\"redispatch\": [(1,+10)]})\n",
    "act.is_ambiguous()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The (desired) setpoint is not the implementation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As said in the preamble of this section, the target dispatching, what we want to achieve (the target), is not equal to the implemented dispatching. So that we can see the operations that are actually being performed, both of these values are present in the observation, as shown in the cell below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "actual dispatch at time step 0: [ 5.  -2.5  0.   0.  -2.5]\n"
     ]
    }
   ],
   "source": [
    "observed = []\n",
    "# perform a valid redispatching action\n",
    "env.set_id(0)  # make sure to use the same environment input data.\n",
    "obs_init = env.reset()  # reset the environment\n",
    "act = env.action_space()\n",
    "act = env.action_space({\"redispatch\": [(0,+5)]})\n",
    "# act = env.action_space({\"redispatch\": [(0,0)]})\n",
    "obs, reward, done, info = env.step(act)\n",
    "print(\"actual dispatch at time step 0: {}\".format(obs.actual_dispatch))\n",
    "observed.append(obs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The target dispatch is exactly what we wanted, eg the generator 0 has increased its production by $5MW$. To compensate for this increase, both generator 1 and 4 have seen their setpoint diminish by 2.5MW.\n",
    "\n",
    "Let's draw the generators' base productions in this scenario, and what is implemented with the current redispatching :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x7f1d9efa4b20>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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HR0drFq1ar2PSIRG6/vYY49l2LBhnH/++Wtruu222xg3bhxjxozh5JNPZsWKFQD89Kc/Zf/992fMmDHcdNNN9R9YqW6ZWcsLOBSYS+Pab9C43nsecAPw8WqZy4BzetrWwQcfnFuVRj9UZV/abI8++uibJxT43eywww6ZmblmzZqcNGlS/sd//EdmZh511FE5b968zMy877778oMf/GBmZp5wwgk5ffr0zMz853/+57XrL1y4MA888MDMzDz33HPz+9//fmZm/v73v8+VK1fmwoULE8h77rknMzPPPPPM/NrXvpaZmcuWLVtbz+mnn5633HJLZmYeeeSROWvWrLXbGTp0aP7617/OzMyXXnopX3vttbzyyitz6NChuXz58ly1alXus88++fTTT2d3d3ceccQRuWLFiszMvOiii/LCCy/MVatWZXt7e86bNy//8Ic/5Mknn5zHHXfcxv1+pIKArtxAttV5Dfh+GjdbPQj8J43W9jTgb4C/jogngd2AK+qqQdparVq1io6ODvbYYw+ef/55Jk6cyIoVK/jVr37FySefTEdHB5/5zGdYunQpADNnzuTUU08F4JOf/OR6tzlu3Dj+/u//nosvvpjFixczcOBAAPbee2/Gjx8PwOmnn84999wDvP0jC9/wxBNPrPcRiQBHH300gwYNYsCAARxwwAEsXryY++67j0cffZTx48fT0dHB9OnTWbx4MY8//jhDhw5l2LBhRASnn376FjyaUhm1PowhM/8v8H/fMnkBMLbO/UpbuzeuAa9cuZJjjjmGqVOncsYZZ7Dzzjsze/bs9a4TPVxf/sQnPsGhhx7KT37yEz784Q9z+eWXs++++/639SKix0cWboz1PQoxM5k4cSLXXnvtm5bd0M8k9WZ9riesLX2/TE332EgbZfvtt+eb3/wm//iP/8j222/P0KFDueGGG4DG5aWHH34YgPHjx/PDH/4QgGuuuWa921qwYAH77rsvn/vc5zjxxBN55JFHAHj66ae59957AfjBD37ABz7wgbd9ZOFOO+209jrvfvvtt95HJG7IYYcdxsyZM3nyyScBeOWVV5g3bx77778/ixYt4qmnngL4bwEt9UZ9LoC1ZZT+EOMHmT866KCDGDVqFNdeey3XXHMNV1xxBaNHj+bAAw/k5ptvBuDSSy9l6tSpjBw5cu0NW291/fXXM2LECDo6Opgz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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Create a matplot figure\n",
    "redisp_fig = plt.figure()\n",
    "ax = redisp_fig.add_axes([0,0,1,1])\n",
    "# X axis is the generators\n",
    "x_gens = np.arange(obs.n_gen)\n",
    "# Y axis is the production in MW\n",
    "y_scenario_p = obs.prod_p - obs.actual_dispatch\n",
    "y_redisp_p = obs.prod_p\n",
    "# Blue bars for scenario productions\n",
    "ax.bar(x_gens - 0.2, y_scenario_p, color = 'b', width = 0.4)\n",
    "# Red bars for production with redispatch\n",
    "ax.bar(x_gens + 0.2, y_redisp_p, color = 'r', width = 0.4)\n",
    "# Set some legend to describe what's above\n",
    "ax.set_ylabel('MW')\n",
    "ax.set_xlabel('Generator ID')\n",
    "ax.legend(labels=['Scenario', 'Redispatched'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the following cell, we won't be performing any redispatching action. We will simply do nothing. This example is here to illustrate that, until the original redispatching action is removed (ie until the opposite command is sent), grid2op will continue to apply the previous redispatching configuration over time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "actual dispatch at time step 1: [ 5.  -2.5  0.   0.  -2.5]\n",
      "actual dispatch at time step 2: [ 5.  -2.5  0.   0.  -2.5]\n"
     ]
    }
   ],
   "source": [
    "donothing = env.action_space()\n",
    "obs1, reward, done, info = env.step(donothing)\n",
    "print(\"actual dispatch at time step 1: {}\".format(obs1.actual_dispatch))\n",
    "observed.append(obs1)\n",
    "obs2, reward, done, info = env.step(donothing)\n",
    "print(\"actual dispatch at time step 2: {}\".format(obs2.actual_dispatch))\n",
    "observed.append(obs2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, the original redispatching action was to increase the setpoint of generator 0 by $5MW$. If we want to remove this, we need to decrease its setpoint by $5MW$ :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "actual dispatch at time step 3: [ 1.310003  -0.6550015  0.         0.        -0.6550015]\n"
     ]
    }
   ],
   "source": [
    "act = env.action_space({\"redispatch\": [(0,-5)]})\n",
    "obs3, reward, done, info = env.step(act)\n",
    "print(\"actual dispatch at time step 3: {}\".format(obs3.actual_dispatch))\n",
    "observed.append(obs3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we see in the cell above, there are still residuals on the dispatch. This is because of the physical limit of the ramp of the generator 0. We wanted it to return to its original setpoint value, but at the same time step, the environment also modified the setpoint of this generator by -1.3MW. Therefore, the total desired decrease for the setpoint of generator 0 was $5+1.3 = 6.3 > maxrampdown$ and the action could not be immediately and completely performed. Grid2op capped the redispatch occuring at this timestep to $maxrampdown$.\n",
    "\n",
    "That is why we can see a small part of the dispatch left. If we wait for another timestep and do nothing, the generator will likely be in order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "actual dispatch at time step 4: [ 0.000000e+00  1.110223e-16  0.000000e+00  0.000000e+00 -1.110223e-16]\n",
      "actual dispatch at time step 5: [ 0.000000e+00  1.110223e-16  0.000000e+00  0.000000e+00 -1.110223e-16]\n"
     ]
    }
   ],
   "source": [
    "obs4, reward, done, info = env.step(donothing)\n",
    "print(\"actual dispatch at time step 4: {}\".format(obs4.actual_dispatch))\n",
    "observed.append(obs4)\n",
    "obs5, reward, done, info = env.step(donothing)\n",
    "print(\"actual dispatch at time step 5: {}\".format(obs5.actual_dispatch))\n",
    "observed.append(obs5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now everything is set up as it should be. The system is back to its original state. Let's see what happens if we ask to increase again the value of this generator 0."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "actual dispatch at time step 6: [ 4.6900043 -2.3450022  0.         0.        -2.3450022]\n",
      "actual dispatch at time step 7: [ 5.  -2.5  0.   0.  -2.5]\n",
      "actual dispatch at time step 8: [ 5.  -2.5  0.   0.  -2.5]\n"
     ]
    }
   ],
   "source": [
    "act = env.action_space({\"redispatch\": [(0,+5)]})\n",
    "# act = env.action_space({\"redispatch\": [(0,0)]})\n",
    "obs6, reward, done, info = env.step(act)\n",
    "print(\"actual dispatch at time step 6: {}\".format(obs6.actual_dispatch))\n",
    "observed.append(obs6)\n",
    "obs7, reward, done, info = env.step(donothing)\n",
    "print(\"actual dispatch at time step 7: {}\".format(obs7.actual_dispatch))\n",
    "observed.append(obs7)\n",
    "obs8, reward, done, info = env.step(donothing)\n",
    "print(\"actual dispatch at time step 8: {}\".format(obs8.actual_dispatch))\n",
    "observed.append(obs8)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This time we see that the full (valid) redispatching action is not applied completely. This is due to the same phenomenon that occurred previously. The environment increased the value of this generator, and at the same time, we also asked to increase it by its \"max ramp up\" value. Consequently, our action was \"capped\" and only  4.7MW (out of 5) were indeed added to the generator's production. At the next time step, the action would be fully implemented.\n",
    "\n",
    "To conclude on redispatching, we saw that there is a difference between the value we ask for, and the value that is implemented by the environment. This is mainly because:\n",
    "\n",
    "- the implemented vector should sum to 0.\n",
    "- if a redispatching is close to the maximum value it can take (due to ramping limitation or hard limitations) and if at the same time the environment itself \"wants\" to increase this value, physical limitations have to be respected.\n",
    "\n",
    "Redispatching actions also last in time. One action must be explicitely canceled to be reset to 0. This cancellation, because of the limitations mentionned above, can take a few time steps to be fully effective."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To summarize, we can look at the productions over time for generators 0 & 4:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x7f1d9f273be0>"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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4IknOO5GvE4Bq4iIiIiIeEaHDsBffwEVKpheyc2pUAH48ktg40bgo49MryYoKWAVERERERHPyZYNiI5miW10tOnVZF6vXsAjj7B78LZtplcTdBSwioiIiIiIZx06BHz1FfDii6ZXknk2G7OsJUvyPG5CgukVBRUFrCIiIiIi4llNmgAjRwKhocCcOaZXk3lFiwLTpwN79wJvvWV6NUFFAauIiIiIiHje0KFAixac0XrypOnVZF6nTswQf/opsHq16dUEDQWsIiIiIiLieTlyADNmAImJwKuvml7NzRk3DqhRA+jbF7h40fRqgoICVhERERER8Y5q1YC5c4HPPjO9kpuTNy8wcyZw+jSbSInHKWAVERERERHv6dIFKFsWcDj8cz5rs2bsGDxrFvDjj6ZXE/AUsIqIiIiIiPf16gV07gwkJZleSea99RZw++3Ac88Bp06ZXk1AU8AqIiIiIiLe17MnsHUrMGaM6ZVkXo4cLA1OSAD69QMsy/SKApYCVhERERER8b6HHgKeeAJ4/31g0ybTq8m86tWBjz8Gli8HpkwxvZqAZbP8YDegadOm1pYtW0wvQ0RERERE3CkmBqhfH8iZE9i+HciXz/SKMseyeCZ37Vpg2zZ2EJabYrPZtlqW1TTl7cqwioiIiIiIGYUKAd9/DyQnA0ePml5N5tlswDffAHnyAI8/7p/ncX2cAlYRERERETGnXTtg3z6gdm3TK7k5ZcsCU6cCmzcDY8eaXk3AUcAqIiIiIiJm5cwJXL0KjBrln6NuHn4YeOwxYPRo4K+/TK8moChgFRERERER88LD2YDpuef8s+vuF18w2/r448Dly6ZXEzAUsIqIiIiIiHl16zJD+dNPwKxZpleTeYUL8zzugQPAkCGmVxMwFLCKiIiIiIhvGDwYaN0aePFF4Ngx06vJvLvuAl57DZg8GVi2zPRqAoICVhERERER8Q3ZswMzZgAOB/Dss6ZXc3Pefx+oUwfo1w+IijK9Gr+ngFVERERERHzHbbexJHj8eNMruTm5cwMzZ7J51PPP++d5XB+igFVERERERHxL9+480woAcXFm13IzGjUC3nsPmDsXCA01vRq/poBVRERERER806uvAm3acOSNv3njDaBVK2DgQOD4cdOr8VsKWEVERERExDfddRewYwfw7rumV5J5zvO4yclA3748lyuZpoBVRERERER8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\n",
      "text/plain": [
       "<Figure size 1152x648 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Create a matplot figure\n",
    "redisp_fig = plt.figure(figsize=(16, 9))\n",
    "# X axis is the timesteps\n",
    "x_gens = np.arange(len(observed), dtype=np.int32)\n",
    "# Y axis is the production in MW\n",
    "y_scenario_p_0 = [o.prod_p[0] - o.actual_dispatch[0] for o in observed] \n",
    "y_redisp_p_0 = [o.prod_p[0] for o in observed]\n",
    "y_scenario_p_4 = [o.prod_p[4] - o.actual_dispatch[4] for o in observed] \n",
    "y_redisp_p_4 = [o.prod_p[4] for o in observed]\n",
    "# Blue lines for gen 0\n",
    "plt.plot(x_gens, y_scenario_p_0, 'b', x_gens, y_redisp_p_0, 'b--')\n",
    "# Red lines for gen 4\n",
    "plt.plot(x_gens, y_scenario_p_4, 'r', x_gens, y_redisp_p_4, 'r--')\n",
    "# Set some legend to describe what's above\n",
    "plt.ylabel('MW')\n",
    "plt.xlabel('Timesteps')\n",
    "plt.legend(labels=['Scenario gen 0', 'Redispatched gen 0', 'Scenario gen 4', 'Redispatched gen 4'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example of use: economic dispatch problem"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "f6a2a2cd05414303a8766fa566c6fc37",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "HBox(children=(FloatProgress(value=0.0, description='step', style=ProgressStyle(description_width='initial')),…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "The cumulative reward with this agent is 121369\n"
     ]
    }
   ],
   "source": [
    "agent = DoNothingAgent(env.action_space)\n",
    "done = False\n",
    "reward = env.reward_range[0]\n",
    "\n",
    "env.set_id(0)  # make sure to evaluate the models on the same experiments\n",
    "obs = env.reset()\n",
    "cum_reward = 0\n",
    "nrow = env.chronics_handler.max_timestep() if max_iter <= 0 else max_iter\n",
    "gen_p = np.zeros((nrow, env.n_gen))\n",
    "gen_p_setpoint = np.zeros((nrow, env.n_gen))\n",
    "load_p = np.zeros((nrow, env.n_load))\n",
    "rho = np.zeros((nrow, env.n_line))\n",
    "i = 0\n",
    "with tqdm(total=max_iter, desc=\"step\") as pbar:\n",
    "    while not done:\n",
    "        act = agent.act(obs, reward, done)\n",
    "        obs, reward, done, info = env.step(act)\n",
    "        data_generator = env.chronics_handler.real_data.data\n",
    "        gen_p_setpoint[i,:] = data_generator.prod_p[data_generator.current_index, :]\n",
    "        gen_p[i,:] = obs.prod_p\n",
    "        load_p[i,:] = obs.load_p\n",
    "        rho[i,:] = obs.rho\n",
    "        cum_reward += reward\n",
    "        i += 1\n",
    "        pbar.update(1)\n",
    "        if i >= max_iter:\n",
    "            break\n",
    "print(\"The cumulative reward with this agent is {:.0f}\".format(cum_reward))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's try to redispatch as much production as possible to the cheapest generator, and leave the rest unchanged."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "b4eac187f6cf4dd5841ee682a8542f85",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "HBox(children=(FloatProgress(value=0.0, description='step', style=ProgressStyle(description_width='initial')),…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "The cumulative reward with this agent is 97832\n"
     ]
    }
   ],
   "source": [
    "class GreedyEconomic(BaseAgent):\n",
    "    def __init__(self, action_space):\n",
    "        super().__init__(action_space)\n",
    "        self.do_nothing = action_space()\n",
    "        \n",
    "    def act(self, obs, reward, done):\n",
    "        act = self.do_nothing\n",
    "        if obs.prod_p[0] < obs.gen_pmax[0] - 1 and \\\n",
    "        obs.target_dispatch[0] < (obs.gen_pmax[0] - obs.gen_max_ramp_up[0]) - 1 and\\\n",
    "        obs.prod_p[0] > 0.:\n",
    "            # if the cheapest generator is significantly bellow its maximum cost\n",
    "            if obs.target_dispatch[0] < obs.gen_pmax[0]:\n",
    "                #in theory i can still ask for more\n",
    "                act = env.action_space({\"redispatch\": [(0, obs.gen_max_ramp_up[0])]})\n",
    "        return act\n",
    "    \n",
    "agent = GreedyEconomic(env.action_space)\n",
    "done = False\n",
    "reward = env.reward_range[0]\n",
    "\n",
    "env.set_id(0) # reset the env to the same id\n",
    "obs = env.reset()\n",
    "cum_reward = 0\n",
    "nrow = env.chronics_handler.max_timestep() if max_iter <= 0 else max_iter\n",
    "gen_p = np.zeros((nrow, env.n_gen))\n",
    "gen_p_setpoint = np.zeros((nrow, env.n_gen))\n",
    "load_p = np.zeros((nrow, env.n_load))\n",
    "rho = np.zeros((nrow, env.n_line))\n",
    "i = 0\n",
    "with tqdm(total=max_iter, desc=\"step\") as pbar:\n",
    "    while not done:\n",
    "        act = agent.act(obs, reward, done)\n",
    "        obs, reward, done, info = env.step(act)\n",
    "#         print(\"act: {}\".format(act))\n",
    "#         print(\"info: {}\".format(info['exception']))\n",
    "#         if info['exception'] is not None:\n",
    "        if np.abs(np.sum(obs.actual_dispatch)) > 1e-2:\n",
    "            pdb.set_trace()\n",
    "        data_generator = env.chronics_handler.real_data.data\n",
    "        gen_p_setpoint[i,:] = data_generator.prod_p[data_generator.current_index, :]\n",
    "        gen_p[i,:] = obs.prod_p\n",
    "        load_p[i,:] = obs.load_p\n",
    "        rho[i,:] = obs.rho\n",
    "        cum_reward += reward\n",
    "        i += 1\n",
    "        pbar.update(1)\n",
    "        if i >= max_iter:\n",
    "            break\n",
    "print(\"The cumulative reward with this agent is {:.0f}\".format(cum_reward))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, that second agent performed worse than the `DoNothing` agent, demonstrating that having the cheapest generators produce the most energy is not always the best solution."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
